<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>PDFMiner</title>
</head>
<body>

<div align=right class=lastmod>
<!-- hhmts start -->
Last Modified: Mon Sep 26 09:04:15 UTC 2016
<!-- hhmts end -->
</div>

<h1>PDFMiner</h1>
<p>
Python PDF parser and analyzer

<p>
<a href="http://www.unixuser.org/~euske/python/pdfminer/index.html">Homepage</a>
&nbsp;
<a href="#changes">Recent Changes</a>
&nbsp;
<a href="programming.html">PDFMiner API</a>

<ul>
<li> <a href="#intro">What's It?</a>
<li> <a href="#download">Download</a>
<li> <a href="#wheretoask">Where to Ask</a>
<li> <a href="#install">How to Install</a> 
  <ul> 
    <li> <a href="#cmap">CJK languages support</a>
  </ul>
<li> <a href="#tools">Command Line Tools</a>
  <ul>
    <li> <a href="#pdf2txt">pdf2txt.py</a>
    <li> <a href="#dumppdf">dumppdf.py</a>
    <li> <a href="programming.html">PDFMiner API</a>
  </ul>
<li> <a href="#changes">Changes</a>
<li> <a href="#todo">TODO</a>
<li> <a href="#related">Related Projects</a>
<li> <a href="#license">Terms and Conditions</a>
</ul>

<h2><a name="intro">What's It?</a></h2>
<p>
PDFMiner is a tool for extracting information from PDF documents.
Unlike other PDF-related tools, it focuses entirely on getting 
and analyzing text data. PDFMiner allows one to obtain
the exact location of text in a page, as well as 
other information such as fonts or lines.
It includes a PDF converter that can transform PDF files
into other text formats (such as HTML). It has an extensible
PDF parser that can be used for other purposes than text analysis.

<p>
<h3>Features</h3>
<ul>
<li> Written entirely in Python. (for version 2.6 or newer)
<li> Parse, analyze, and convert PDF documents.
<li> PDF-1.7 specification support. (well, almost)
<li> CJK languages and vertical writing scripts support.
<li> Various font types (Type1, TrueType, Type3, and CID) support.
<li> Basic encryption (RC4) support.
<li> PDF to HTML conversion (with a sample converter web app).
<li> Outline (TOC) extraction.
<li> Tagged contents extraction.
<li> Reconstruct the original layout by grouping text chunks.
</ul>
<p>
PDFMiner is about 20 times slower than 
other C/C++-based counterparts such as XPdf.

<P>
<strong>Online Demo:</strong> (pdf -&gt; html conversion webapp)<br>
<a href="http://pdf2html.tabesugi.net:8080/">
http://pdf2html.tabesugi.net:8080/
</a>

<h3><a name="download">Download</a></h3>
<p>
<strong>Source distribution:</strong><br>
<a href="http://pypi.python.org/pypi/pdfminer/">
http://pypi.python.org/pypi/pdfminer/
</a>

<P>
<strong>github:</strong><br>
<a href="https://github.com/euske/pdfminer/">
https://github.com/euske/pdfminer/
</a>

<h3><a name="wheretoask">Where to Ask</a></h3>
<p>
<p>
<strong>Questions and comments:</strong><br>
<a href="http://groups.google.com/group/pdfminer-users/">
http://groups.google.com/group/pdfminer-users/
</a>


<h2><a name="install">How to Install</a></h2>
<ol>
<li> Install <a href="http://www.python.org/download/">Python</a> 2.6 or newer.
     (<font color=red><strong>Python 3 is not supported.</strong></font>)
<li> Download the <a href="#source">PDFMiner source</a>.
<li> Unpack it.
<li> Run <code>setup.py</code> to install:<br>
<blockquote><pre>
# <strong>python setup.py install</strong>
</pre></blockquote>
<li> Do the following test:<br>
<blockquote><pre>
$ <strong>pdf2txt.py samples/simple1.pdf</strong>
Hello

World

Hello

World

H e l l o

W o r l d

H e l l o

W o r l d
</pre></blockquote>
<li> Done!
</ol>

<h3><a name="cmap">For CJK languages</a></h3>
<p>
In order to process CJK languages, you need an additional step to take
during installation:
<blockquote><pre>
# <strong>make cmap</strong>
python tools/conv_cmap.py pdfminer/cmap Adobe-CNS1 cmaprsrc/cid2code_Adobe_CNS1.txt
reading 'cmaprsrc/cid2code_Adobe_CNS1.txt'...
writing 'CNS1_H.py'...
...
<em>(this may take several minutes)</em>

# <strong>python setup.py install</strong>
</pre></blockquote>

<p>
On Windows machines which don't have <code>make</code> command, 
paste the following commands on a command line prompt:
<blockquote><pre>
<strong>mkdir pdfminer\cmap</strong>
<strong>python tools\conv_cmap.py -c B5=cp950 -c UniCNS-UTF8=utf-8 pdfminer\cmap Adobe-CNS1 cmaprsrc\cid2code_Adobe_CNS1.txt</strong>
<strong>python tools\conv_cmap.py -c GBK-EUC=cp936 -c UniGB-UTF8=utf-8 pdfminer\cmap Adobe-GB1 cmaprsrc\cid2code_Adobe_GB1.txt</strong>
<strong>python tools\conv_cmap.py -c RKSJ=cp932 -c EUC=euc-jp -c UniJIS-UTF8=utf-8 pdfminer\cmap Adobe-Japan1 cmaprsrc\cid2code_Adobe_Japan1.txt</strong>
<strong>python tools\conv_cmap.py -c KSC-EUC=euc-kr -c KSC-Johab=johab -c KSCms-UHC=cp949 -c UniKS-UTF8=utf-8 pdfminer\cmap Adobe-Korea1 cmaprsrc\cid2code_Adobe_Korea1.txt</strong>
<strong>python setup.py install</strong>
</pre></blockquote>

<h2><a name="tools">Command Line Tools</a></h2>
<p>
PDFMiner comes with two handy tools:
<code>pdf2txt.py</code> and <code>dumppdf.py</code>.

<h3><a name="pdf2txt">pdf2txt.py</a></h3>
<p>
<code>pdf2txt.py</code> extracts text contents from a PDF file.
It extracts all the text that are to be rendered programmatically,
i.e. text represented as ASCII or Unicode strings.
It cannot recognize text drawn as images that would require optical character recognition.
It also extracts the corresponding locations, font names, font sizes, writing
direction (horizontal or vertical) for each text portion.
You need to provide a password for protected PDF documents when its access is restricted.
You cannot extract any text from a PDF document which does not have extraction permission.

<p>
<strong>Note:</strong>
Not all characters in a PDF can be safely converted to Unicode.

<h4>Examples</h4>
<blockquote><pre>
$ <strong>pdf2txt.py -o output.html samples/naacl06-shinyama.pdf</strong>
(extract text as an HTML file whose filename is output.html)

$ <strong>pdf2txt.py -V -c euc-jp -o output.html samples/jo.pdf</strong>
(extract a Japanese HTML file in vertical writing, CMap is required)

$ <strong>pdf2txt.py -P mypassword -o output.txt secret.pdf</strong>
(extract a text from an encrypted PDF file)
</pre></blockquote>

<h4>Options</h4>
<dl>
<dt> <code>-o <em>filename</em></code> 
<dd> Specifies the output file name.
By default, it prints the extracted contents to stdout in text format.
<p>
<dt> <code>-p <em>pageno[,pageno,...]</em></code> 
<dd> Specifies the comma-separated list of the page numbers to be extracted. 
Page numbers start at one.
By default, it extracts text from all the pages.
<p>
<dt> <code>-c <em>codec</em></code> 
<dd> Specifies the output codec.
<p>
<dt> <code>-t <em>type</em></code> 
<dd> Specifies the output format. The following formats are currently supported.
<ul>
<li> <code>text</code> : TEXT format. (Default)
<li> <code>html</code> : HTML format. Not recommended for extraction purposes because the markup is messy.
<li> <code>xml</code> : XML format. Provides the most information.
<li> <code>tag</code> : "Tagged PDF" format. A tagged PDF has its own contents annotated with
HTML-like tags. pdf2txt tries to extract its content streams rather than inferring its text locations.
Tags used here are defined in the PDF specification (See &sect;10.7 "<em>Tagged PDF</em>").
</ul>
<p>
<dt> <code>-I <em>image_directory</em></code> 
<dd> Specifies the output directory for image extraction.
Currently only JPEG images are supported.
<p>
<dt> <code>-M <em>char_margin</em></code> 
<dt> <code>-L <em>line_margin</em></code> 
<dt> <code>-W <em>word_margin</em></code> 
<dd> These are the parameters used for layout analysis.
In an actual PDF file, text portions might be split into several chunks
in the middle of its running, depending on the authoring software.
Therefore, text extraction needs to splice text chunks.
In the figure below, two text chunks whose distance is closer than
the <em>char_margin</em> (shown as <em><font color="red">M</font></em>) is considered
continuous and get grouped into one. Also, two lines whose distance is closer than
the <em>line_margin</em> (<em><font color="blue">L</font></em>) is grouped
as a text box, which is a rectangular area that contains a "cluster" of text portions.
Furthermore, it may be required to insert blank characters (spaces) as necessary
if the distance between two words is greater than the <em>word_margin</em> 
(<em><font color="green">W</font></em>), as a blank between words might not be
represented as a space, but indicated by the positioning of each word.
<p>
Each value is specified not as an actual length, but as a proportion of
the length to the size of each character in question. The default values 
are M = 2.0, L = 0.5, and W = 0.1, respectively.
<table style="border:2px gray solid; margin: 10px; padding: 10px;"><tr>
<td style="border-right:1px red solid" align=right>&rarr;</td>
<td style="border-left:1px red solid" colspan="4" align=left>&larr; <em><font color="red">M</font></em></td>
<td></td>
</tr><tr>
<td style="border:1px solid"><code>Q u i</code></td>
<td style="border:1px solid"><code>c k</code></td>
<td width="10px"></td>
<td style="border:1px solid"><code>b r o w</code></td>
<td style="border:1px solid"><code>n &nbsp; f o x</code></td>
<td style="border-bottom:1px blue solid" align=right>&darr;</td>
</tr><tr>
<td style="border-right:1px green solid" colspan="2" align=right>&rarr;</td><td></td>
<td style="border-left:1px green solid" colspan="2" align=left>&larr; <em><font color="green">W</font></em></td>
<td rowspan="2" valign=center align=center><em><font color="blue">L</font></em></td>
</tr><tr height="10px">
</tr><tr>
<td style="padding:0px;" colspan="5">
<table style="border:1px solid"><tr><td><code>j u m p s</code></td><td>...</td></tr></table>
</td>
<td style="border-top:1px blue solid" align=right>&uarr;</td>
</tr></table>
<p>
<dt> <code>-F <em>boxes_flow</em></code> 
<dd> Specifies how much a horizontal and vertical position of a text matters
when determining a text order. The value should be within the range of 
-1.0 (only horizontal position matters) to +1.0 (only vertical position matters).
When this value is out of the range (e.g. +2), a simpler ordering rule is used.
The default value is 0.5.
<p>
<dt> <code>-C</code> 
<dd> Suppress object caching. 
This will reduce the memory consumption but also slows down the process.
<p>
<dt> <code>-n</code> 
<dd> Suppress layout analysis.
<p>
<dt> <code>-A</code> 
<dd> Forces to perform layout analysis for all the text strings, 
including text contained in figures.
<p>
<dt> <code>-V</code> 
<dd> Allows vertical writing detection.
<p>
<dt> <code>-Y <em>layout_mode</em></code> 
<dd> Specifies how the page layout should be preserved. (Currently only applies to HTML format.)
<ul>
<li> <code>exact</code> : preserve the exact location of each individual character (a large and messy HTML).
<li> <code>normal</code> : preserve the location and line breaks in each text block. (Default)
<li> <code>loose</code> : preserve the overall location of each text block.
</ul>
<p>
<dt> <code>-E <em>extractdir</em></code>
<dd> Specifies the extraction directory of embedded files.
<p>
<dt> <code>-s <em>scale</em></code> 
<dd> Specifies the output scale. Can be used in HTML format only.
<p>
<dt> <code>-m <em>maxpages</em></code> 
<dd> Specifies the maximum number of pages to extract.
By default, it extracts all the pages in a document.
<p>
<dt> <code>-P <em>password</em></code> 
<dd> Provides the user password to access PDF contents.
<p>
<dt> <code>-d</code> 
<dd> Increases the debug level.
</dl>

<hr noshade>

<h3><a name="dumppdf">dumppdf.py</a></h3>
<p>
<code>dumppdf.py</code> dumps the internal contents of a PDF file
in pseudo-XML format. This program is primarily for debugging purposes,
but it's also possible to extract some meaningful contents
(such as images).

<h4>Examples</h4>
<blockquote><pre>
$ <strong>dumppdf.py -a foo.pdf</strong>
(dump all the headers and contents, except stream objects)

$ <strong>dumppdf.py -T foo.pdf</strong>
(dump the table of contents)

$ <strong>dumppdf.py -r -i6 foo.pdf &gt; pic.jpeg</strong>
(extract a JPEG image)
</pre></blockquote>

<h4>Options</h4>
<dl>
<dt> <code>-a</code> 
<dd> Instructs to dump all the objects.
By default, it only prints the document trailer (like a header).
<p>
<dt> <code>-i <em>objno,objno, ...</em></code> 
<dd> Specifies PDF object IDs to display.
Comma-separated IDs, or multiple <code>-i</code> options are accepted.
<p>
<dt> <code>-p <em>pageno,pageno, ...</em></code> 
<dd> Specifies the page number to be extracted.
Comma-separated page numbers, or multiple <code>-p</code> options are accepted.
Note that page numbers start at one, not zero.
<p>
<dt> <code>-r</code> (raw)
<dt> <code>-b</code> (binary)
<dt> <code>-t</code> (text)
<dd> Specifies the output format of stream contents.
Because the contents of stream objects can be very large,
they are omitted when none of the options above is specified.
<p>
With <code>-r</code> option, the "raw" stream contents are dumped without decompression. 
With <code>-b</code> option, the decompressed contents are dumped as a binary blob.
With <code>-t</code> option, the decompressed contents are dumped in a text format,
similar to <code>repr()</code> manner. When 
<code>-r</code> or <code>-b</code> option is given, 
no stream header is displayed for the ease of saving it to a file.
<p>
<dt> <code>-T</code> 
<dd> Shows the table of contents.
<p>
<dt> <code>-E <em>directory</em></code> 
<dd> Extracts embedded files from the pdf into the given directory.
<p>
<dt> <code>-P <em>password</em></code> 
<dd> Provides the user password to access PDF contents.
<p>
<dt> <code>-d</code> 
<dd> Increases the debug level.
</dl>

<h2><a name="changes">Changes</a></h2>
<ul>
<li> 2014/03/28: Further bugfixes.
<li> 2014/03/24: Bugfixes and improvements for fauly PDFs.<br>
API changes:
 <ul>
 <li> <code>PDFDocument.initialize()</code> method is removed and no longer needed.
  A password is given as an argument of a PDFDocument constructor.
 </ul>
<li> 2013/11/13: Bugfixes and minor improvements.<br>
As of November 2013, there were a few changes made to the PDFMiner API
prior to October 2013. This is the result of code restructuring.  Here
is a list of the changes:
 <ul>
 <li> <code>PDFDocument</code> class is moved to <code>pdfdocument.py</code>.
 <li> <code>PDFDocument</code> class now takes a <code>PDFParser</code> object as an argument.
 <li> <code>PDFDocument.set_parser()</code> and <code>PDFParser.set_document()</code> is removed.
 <li> <code>PDFPage</code> class is moved to <code>pdfpage.py</code>.
 <li> <code>process_pdf</code> function is implemented as <code>PDFPage.get_pages</code>.
</ul>
<li> 2013/10/22: Sudden resurge of interests. API changes.
Incorporated a lot of patches and robust handling of broken PDFs.
<li> 2011/05/15: Speed improvements for layout analysis.
<li> 2011/05/15: API changes. <code>LTText.get_text()</code> is added.
<li> 2011/04/20: API changes. LTPolygon class was renamed as LTCurve.
<li> 2011/04/20: LTLine now represents horizontal/vertical lines only. Thanks to Koji Nakagawa.
<li> 2011/03/07: Documentation improvements by Jakub Wilk. Memory usage patch by Jonathan Hunt.
<li> 2011/02/27: Bugfixes and layout analysis improvements. Thanks to fujimoto.report.
<li> 2010/12/26: A couple of bugfixes and minor improvements. Thanks to Kevin Brubeck Unhammer and Daniel Gerber.
<li> 2010/10/17: A couple of bugfixes and minor improvements. Thanks to standardabweichung and Alastair Irving.
<li> 2010/09/07: A minor bugfix. Thanks to Alexander Garden.
<li> 2010/08/29: A couple of bugfixes. Thanks to Sahan Malagi, pk, and Humberto Pereira.
<li> 2010/07/06: Minor bugfixes. Thanks to Federico Brega.
<li> 2010/06/13: Bugfixes and improvements on CMap data compression. Thanks to Jakub Wilk.
<li> 2010/04/24: Bugfixes and improvements on TOC extraction. Thanks to Jose Maria.
<li> 2010/03/26: Bugfixes. Thanks to Brian Berry and Lubos Pintes.
<li> 2010/03/22: Improved layout analysis. Added regression tests.
<li> 2010/03/12: A couple of bugfixes. Thanks to Sean Manefield.
<li> 2010/02/27: Changed the way of internal layout handling. (LTTextItem -&gt; LTChar)
<li> 2010/02/15: Several bugfixes. Thanks to Sean.
<li> 2010/02/13: Bugfix and enhancement. Thanks to Andr&eacute; Auzi.
<li> 2010/02/07: Several bugfixes. Thanks to Hiroshi Manabe.
<li> 2010/01/31: JPEG image extraction supported. Page rotation bug fixed. 
<li> 2010/01/04: Python 2.6 warning removal. More doctest conversion.
<li> 2010/01/01: CMap bug fix. Thanks to Winfried Plappert.
<li> 2009/12/24: RunLengthDecode filter added. Thanks to Troy Bollinger.
<li> 2009/12/20: Experimental polygon shape extraction added. Thanks to Yusuf Dewaswala for reporting.
<li> 2009/12/19: CMap resources are now the part of the package. Thanks to Adobe for open-sourcing them.
<li> 2009/11/29: Password encryption bug fixed. Thanks to Yannick Gingras.
<li> 2009/10/31: SGML output format is changed and renamed as XML.
<li> 2009/10/24: Charspace bug fixed. Adjusted for 4-space indentation.
<li> 2009/10/04: Another matrix operation bug fixed. Thanks to Vitaly Sedelnik.
<li> 2009/09/12: Fixed rectangle handling. Able to extract image boundaries.
<li> 2009/08/30: Fixed page rotation handling.
<li> 2009/08/26: Fixed zlib decoding bug. Thanks to Shon Urbas.
<li> 2009/08/24: Fixed a bug in character placing. Thanks to Pawan Jain.
<li> 2009/07/21: Improvement in layout analysis.
<li> 2009/07/11: Improvement in layout analysis. Thanks to Lubos Pintes.
<li> 2009/05/17: Bugfixes, massive code restructuring, and simple graphic element support added. setup.py is supported.
<li> 2009/03/30: Text output mode added.
<li> 2009/03/25: Encoding problems fixed. Word splitting option added. 
<li> 2009/02/28: Robust handling of corrupted PDFs. Thanks to Troy Bollinger.
<li> 2009/02/01: Various bugfixes. Thanks to Hiroshi Manabe.
<li> 2009/01/17: Handling a trailer correctly that contains both /XrefStm and /Prev entries.
<li> 2009/01/10: Handling Type3 font metrics correctly.
<li> 2008/12/28: Better handling of word spacing. Thanks to Christian Nentwich.
<li> 2008/09/06: A sample pdf2html webapp added.
<li> 2008/08/30: ASCII85 encoding filter support.
<li> 2008/07/27: Tagged contents extraction support.
<li> 2008/07/10: Outline (TOC) extraction support.
<li> 2008/06/29: HTML output added. Reorganized the directory structure.
<li> 2008/04/29: Bugfix for Win32. Thanks to Chris Clark.
<li> 2008/04/27: Basic encryption and LZW decoding support added.
<li> 2008/01/07: Several bugfixes. Thanks to Nick Fabry for his vast contribution.
<li> 2007/12/31: Initial release.
<li> 2004/12/24: Start writing the code out of boredom...
</ul>

<h2><a name="todo">TODO</a></h2>
<ul>
<li> <A href="http://www.python.org/dev/peps/pep-0008/">PEP-8</a> and
<a href="http://www.python.org/dev/peps/pep-0257/">PEP-257</a> conformance.
<li> Better documentation.
<li> Better text extraction / layout analysis. (writing mode detection, Type1 font file analysis, etc.)
<li> Crypt stream filter support. (More sample documents are needed!)
</ul>

<h2><a name="related">Related Projects</a></h2>
<ul>
<li> <a href="http://pybrary.net/pyPdf/">pyPdf</a>
<li> <a href="http://www.foolabs.com/xpdf/">xpdf</a>
<li> <a href="http://www.pdfbox.org/">pdfbox</a>
<li> <a href="http://mupdf.com/">mupdf</a>
</ul>

<h2><a name="license">Terms and Conditions</a></h2>
<p>
(This is so-called MIT/X License)
<p>
<small>
Copyright (c) 2004-2013  Yusuke Shinyama &lt;yusuke at cs dot nyu dot edu&gt;
<p>
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
<p>
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
<p>
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</small>

<hr noshade>
<address>Yusuke Shinyama (yusuke at cs dot nyu dot edu)</address>
</body>
